Node.js-Backend見聞錄(07)：關於後端觀念(三)-什麼是Restful-API?

前言

接續關於後端觀念(二)-什麼是API，這次將介紹web後端開發API的設計風格，而這邊將以RESTful來做說明。但在了解RESTful前，我們先進一步的說明request及response。

為了講解request及response，我們先預設一個情境，假設有個API為：

domain: https://www.example.com
GET /hello
response: 
{
    "message": "hello world!" 
}

什麼是 HTTP Request?

由client端所發出，用來跟server端提取資料或傳輸資料的需求都稱之為「HTTP Request」。

例如，我們用GET的HTTP Method去向https://www.example.com/hello
來請求提取資料。其HTTP Headers訊息會：

Client request:

     method: GET /hello HTTP/1.1
     User-Agent: Chrome/62.0.3202.94 Safari/537.36 ...
     Host: www.example.com
     Accept-Language: en, mi
     ...

什麼是 HTTP Headers?
指在HTTP request或HTTP response的訊息中其header部份。它們定義了request或response在傳輸過程中的操作參數。

什麼是 HTTP Response?

由server端所發出，回傳給client端的訊息。主要用來回應client端的request。
例如：承上，Client端向https://www.example.com/hello透過GET的HTTP Method來提取資料後，Server端就會回覆一個response。來讓client取得「hello world!」的訊息。

Server response:

     HTTP/1.1 200 OK
     Date: Mon, 27 Jul 2009 12:28:53 GMT
     Server: Apache
     Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
     ETag: "34aa387-d-1568eb00"
     Accept-Ranges: bytes
     Content-Length: 51
     Vary: Accept-Encoding
     Content-Type: text/plain

     hello world! 

為何我們要先理解request及response的部分，這是因為我們後端在處理API的時候，最主要是在處理收到的request及發送的response。比如：上述例子中有提到的HTTP method的選擇, status code的制定, 以及request URL的命名...等。

讀者這時可能會有疑問。那有沒有什麼規則或風格可以用來奠定出一套適合的制定方式？
答案是有的，我們可以透過RESTful API的設計風格來進行。

註記：
status code會夾雜在response中。以上述例子來說200就是這個response的status code。

什麼是 RESTful 風格？

為一種軟體架構的設計風格，目的在於將不同軟體或程序，使其在網路中互相傳遞訊息的過程簡便化。聽起來很饒舌，但若帶入一個實際案例來看應該可以更容易了解。

假設今天我們要寫一個購物車網站的後台API，每一位後端工程師都會有自己不一樣的寫法。若以「會員系統」來當例子，其功能可能切分為：

• 功能：取得全部會員資料。Method: GET。URL: /api/customerList
• 功能：取得單筆會員資料。Method: GET。URL: /api/customer/?id=?
• 功能：新增會員。Method: POST。URL: /api/customerAdd
• 功能：修改會員。Method: POST。URL: /api/customerEdit
• 功能：刪除會員。Method: POST。URL: /api/customerDelete

但若是使用RESTful的風格，就會變成：

• 功能：取得全部會員資料。Method: GET。URL: /api/customer
• 功能：取得單筆會員資料。Method: GET。URL: /api/customer/:id
• 功能：新增會員。Method: POST。URL: /api/customer
• 功能：修改會員。Method: PUT。URL: /api/customer/:id
• 功能：刪除會員。Method: DELETE。URL: /api/customer/:id

可以觀察到在使用RESTful前跟使用後有些區別，而這些區別的分別為：

• 清楚簡短的API URL
  在URL的部份，相較於使用前的customerAdd。若直接將URL取名為customer，並透過HTTP Method的不同來區別不一樣的功能。能夠達到更清楚簡短的API URL這個目的。

• 對資源的操作
  RESTful會針對每個API的功能來選擇較適合的HTTP Method來對資源進行操作，並使用HTTP status code來表達資源的狀態。

• 傳輸的資源
  在web的前端與後端之間所傳輸的資料類型，RESTful會使用JSON, XML, YAML…等。來進行資料的傳輸。（但現在決大多數都使用JSON格式。）

對於RESTful有初步了解後，我們再更進一步的來看什麼是HTTP Method?及什麼是Status Code?。

什麼是HTTP Method?

HTTP Method也稱之為「Request Method」。它是用來表示client端提出該request的目的，以及client端預期所收到的訊息結果。分有：

• GET: 用來取得URL所標示的目標的資源。
• HEAD: 與GET相同，但是只傳輸status-line和header部份。
• POST: 向目標資源提交資料。
• PUT: 向當前目標資源上傳其最新的內容。
• DELETE: 用來刪除URL所標示的目標資源。
• CONNECT: 建立由目標資源所標示的server端的tunnel。
• OPTIONS: 使server端回傳目標資源所支援的任何HTTP Method。
• TRACE: 用來顯示在目標資源的server端所收到的request。

這部份有想深入了解的人可參考RFC7231文件。

什麼是Status Code ?

如同前面的註記，它出現response中，為一種三位數的整數代碼。當server端收到來自client端的request後，會附加在response上。讓client端在成功收到response的時候，透過status code的情境來得知response是的狀態為何，若是成功則回應相對應的status code，失敗亦同。我們也能藉由status code來得知其成功或失敗的原因為何。

Status code有五大類，分別為：

• 1xx(Informational): 收到request，繼續處理。
• 2xx(Successful): request已經成功接收、理解且被接受。
• 3xx(Redirection): 需要採取進一部的措施才能完成該request。
• 4xx(Client Error): 在request中包含錯誤的語法或是無法實現該request。
• 5xx(Server Error): Server端無法完成有效的request。

小結

簡單來說，我們在寫API的時候可以選擇使用RESTful的設計風格，但未必要完全遵從它的規範，也可以只取部份的設計模式。比如只使用它的HTTP Method的操作方式。最重要還是在開發前先跟前端夥伴一起討論出API的設計原則，才能符合在開發的當下所需的情境。

參考資料

Principles of good RESTful API Design